/**
 * @brief  FATFS底层(diskio) 驱动代码
 * @author 张勇 / 41204@qq.com
 * @date 2022-04-20
 */

#pragma once

#ifdef __cplusplus
extern "C" {
#endif

#include <stdbool.h>
#include "share/std_err.h"
#include "ff.h"


/* Status of Disk Functions */
typedef BYTE    DSTATUS;

/* Results of Disk Functions */
typedef enum
{
    RES_OK = 0,     /* 0: Successful */
    RES_ERROR,      /* 1: R/W Error */
    RES_WRPRT,      /* 2: Write Protected */
    RES_NOTRDY,     /* 3: Not Ready */
    RES_PARERR      /* 4: Invalid Parameter */
} DRESULT;


/*---------------------------------------*/
/* Prototypes for disk control functions */

/// 关于 FatFS 的几个关键参数:
/// - ffconf.h: FF_MIN_SS / FF_MAX_SS：约束底层扇区大小范围，au_size 必须兼容此范围。
/// - MKFS_PARAM: cluster_size / au_size：格式化时指定的簇大小，需适配存储介质特性和应用场景。
/// - f_mkfs(): working buffer 参数, 用于存储 FAT 表、目录条目等临时数据, 必须足够大以处理文件系统的元数据操作，具体需求取决于:
///     文件系统类型（FAT12/16/32）、存储设备的扇区大小（FF_MIN_SS/FF_MAX_SS）等，一般推荐值 = FF_MAX_SS * 4（平衡可靠性和内存占用）
/// 最佳实践：
/// - 根据设备特性设置 FF_MIN_SS 和 FF_MAX_SS。
/// - 在格式化时通过 au_size 明确簇大小，或设为 0 使用默认值。
/// - 确保 au_size 与物理扇区大小、擦除块对齐。
/// - 例如：Flash擦除块为4KB，则 au_size 设为4KB、8KB等。
/// - 如果空间很大，则建议 au_size 设为16KB、32KB等。

/// @brief FatFS-Disk 底层实现数据结构
typedef struct _ffdisk {
    // 配置参数
    BYTE idx;           // pdrv for diskio API: disk_xxx(pdrv, ...)
    void *dev;          // 底层驱动指针
    LBA_t sector_base;  // 起始扇区
    LBA_t sector_count; // 扇区数量
    LBA_t sector_size;  // 扇区大小(字节数)，一个 FAT 扇区至少要 512 字节
    LBA_t au_size;      // 簇(cluster)/分配单元(allocate-unit)大小(字节数), 必须大于等于存储介质擦除块大小且与之对齐，减少写放大。
    BYTE fmt;           // MKFS_PARM.fmt
    
    // 底层 diskio 驱动实现函数
    DSTATUS (*init)  (struct _ffdisk *dev);
    DSTATUS (*status)(struct _ffdisk *dev);
    DRESULT (*read)  (struct _ffdisk *dev, BYTE *buff, LBA_t sector, UINT count);
    DRESULT (*write) (struct _ffdisk *dev, const BYTE *buff, LBA_t sector, UINT count);
    DRESULT (*ioctl) (struct _ffdisk *dev, BYTE cmd, void *buff);    

    // 运行时数据
    bool initialized;   // 是否已经初始化
    FATFS fs;           // 文件系统
} ffdisk_t;

/// @brief 根据 FatFS-Disk 编号，获取底层实现数据结构指针
/// @note 此函数应由应用层自己实现
ffdisk_t* ffdisk_get(BYTE pdrv);

/// @brief 根据 FatFS-Disk 编号，获取底层实现数据结构指针
/// @note 此函数将在 unidrv/ffdiskio.h 中 disk_xxx() 接口函数使用
std_err_t ffdisk_mount(uint8_t idx, const char *vol);

static inline DSTATUS disk_initialize (BYTE pdrv)                                        { ffdisk_t *disk = ffdisk_get(pdrv); return (disk && disk->init)   ? disk->init  (disk)                      : RES_PARERR; }
static inline DSTATUS disk_status (BYTE pdrv)                                            { ffdisk_t *disk = ffdisk_get(pdrv); return (disk && disk->status) ? disk->status(disk)                      : RES_PARERR; }
static inline DRESULT disk_read (BYTE pdrv, BYTE *buff, LBA_t sector, UINT count)        { ffdisk_t *disk = ffdisk_get(pdrv); return (disk && disk->read)   ? disk->read  (disk, buff, sector, count) : RES_PARERR; }
static inline DRESULT disk_write (BYTE pdrv, const BYTE *buff, LBA_t sector, UINT count) { ffdisk_t *disk = ffdisk_get(pdrv); return (disk && disk->write)  ? disk->write (disk, buff, sector, count) : RES_PARERR; }
static inline DRESULT disk_ioctl (BYTE pdrv, BYTE cmd, void *buff)                       { ffdisk_t *disk = ffdisk_get(pdrv); return (disk && disk->ioctl)  ? disk->ioctl (disk, cmd, buff)           : RES_PARERR; }

/// @brief FatFS-Disk 文件读写测试
std_err_t ffdisk_file_rwtest(const char *fname);
/// @brief ISO-C 文件读写测试
std_err_t isoc_file_rwtest(const char *fname);

/* Disk Status Bits (DSTATUS) */

#define STA_NOINIT      0x01    /* Drive not initialized */
#define STA_NODISK      0x02    /* No medium in the drive */
#define STA_PROTECT     0x04    /* Write protected */


/* Command code for disk_ioctrl fucntion */

/* Generic command (Used by FatFs) */
#define CTRL_SYNC           0   /* Complete pending write process (needed at FF_FS_READONLY == 0) */
#define GET_SECTOR_COUNT    1   /* Get media size (needed at FF_USE_MKFS == 1) */
#define GET_SECTOR_SIZE     2   /* Get sector size (needed at FF_MAX_SS != FF_MIN_SS) */
#define GET_BLOCK_SIZE      3   /* Get erase block size (needed at FF_USE_MKFS == 1) */
#define CTRL_TRIM           4   /* Inform device that the data on the block of sectors is no longer used (needed at FF_USE_TRIM == 1) */

/* Generic command (Not used by FatFs) */
#define CTRL_POWER          5   /* Get/Set power status */
#define CTRL_LOCK           6   /* Lock/Unlock media removal */
#define CTRL_EJECT          7   /* Eject media */
#define CTRL_FORMAT         8   /* Create physical format on the media */

/* MMC/SDC specific ioctl command */
#define MMC_GET_TYPE        10  /* Get card type */
#define MMC_GET_CSD         11  /* Get CSD */
#define MMC_GET_CID         12  /* Get CID */
#define MMC_GET_OCR         13  /* Get OCR */
#define MMC_GET_SDSTAT      14  /* Get SD status */
#define ISDIO_READ          55  /* Read data form SD iSDIO register */
#define ISDIO_WRITE         56  /* Write data to SD iSDIO register */
#define ISDIO_MRITE         57  /* Masked write data to SD iSDIO register */

/* ATA/CF specific ioctl command */
#define ATA_GET_REV         20  /* Get F/W revision */
#define ATA_GET_MODEL       21  /* Get model name */
#define ATA_GET_SN          22  /* Get serial number */

#ifdef __cplusplus
}
#endif
